************
INTRODUCTION
************

This file describes how to generate the PHP wrapper code with Melissa DATA's Address Object.


*************
PREREQUISITES
*************

To make use of the Address Object PHP wrapper you will need:

* An installation of a PHP and PHP Sources. Wrapper tested with PHP 5.2.6.

* The Melissa DATA Address Object library and data files installed.
	Library = libmdAddr.so
	Data Files = mdAddr.dat, mdAddr.nat, mdAddr.str, mdAddr.lic

  These files are installed automatically if you run setup.sh.
  
You will need to know the location of these items in order to install and run the PHP wrapper.
  
***Note For PHP 5.3.X:

The current SWIG source file 'mdAddrPHPWrapper.cpp' on the disc is not compatible with PHP Version 5.3.X. The SWIG wrapper was compiled using PHP 5.2.X which uses the zend_error_noreturn() function. This function is no longer avialable in PHP 5.3.X.
 
To use 'mdAddrPHPWrapper.dll' with PHP 5.3.X, you need to make changes in 'mdAddrPHPWrapper.cpp' manually.
Open 'mdAddrPHPWrapper.cpp' in a text editor and replace all zend_error_noreturn with zend_error.
After making these changes in 'mdAddrPHPWrapper.cpp', compile the wrapper again using the 'BuildWrapper.sh' file.


*************
Installation
*************

Copy the entire folder that contains this README.txt into a local directory on your computer.


*****
Setup
*****

Open the BuildWrapper.sh in a text editor. In this file, you must point the script to the
location of the Address Object library files as well as the PHP Source files. 

	set mdAddrPath to the Address Object library directory
	set PHPIncludePath1 to the PHP Source Zend directory
	set PHPIncludePath2 to the PHP Source main directory
	set PHPIncludePath3 to the PHP Source directory
	set PHPIncludePath4 to the PHP Source TSRM directory


*******************
Running the Script
*******************	

Run BuildWrapper.sh (sh BuildWrapper.sh) which should successfully generate
mdAddrPHPWrapper.so.

************
Dependencies
************

You will need to tell PHP where to load the mdAddrPHPWrapper.so extension. 
To do so, you can do one of the following:

	Copy mdAddrPHPWrapper.so to your PHP extension folder, which is specified in your php.ini file.

	or

	Alter the php extension folder by changing php.ini.
		extension_dir ="/usr/local/lib/php/extensions"
		extension_dir ="/usr/lib64/php/modules"

Open a command window. 

	Set LD_LIBRARY_PATH to the Address Object Library directory. This allows mdAddrPHPWrapper.so the ability to find libmdAddr.so.
	
	ex: set LD_LIBRARY_PATH=/usr/lib64/php/modules
	    export LD_LIBRARY_PATH 
		

***If you are using the Address Object PHP wrapper on a webpage hosted by Apache:

	Copy libmdAddr.so and mdAddrPHPWrapper.so into /usr/lib64/php/modules directory or equivalent

	Copy PHPDemo.php and mdAddrPHPWrapper.php into /var/www/html directory

	Copy libmdAddr.so and mdAddrPHPWrapper.so to your PHP extension folder, which is specified in your php.ini file.

	extension_dir ="/usr/lib64/php/modules"

	Edit the /etc/php.ini config file and set the following options.
		Memory_limit=512M
		Display_errors=on

	Put the Object's Data files in the html directory, so there are no permission issues.
		/var/www/html/addrdata

	****Permanently add LD_LIBRARY_PATH for Apache****
		As an administrator touch a new file called md.conf file in the /etc/ld.so.conf.d directory

		add this line to the md.conf file 
		/usr/lib64/php/modules

		As SU run /sbin/ldconfig and restart Apache

		Open the PHP demo in the browser. http://localhost/PHPDemo.php
		You can also run the interactive example: http://localhost/AddressObjectPHPSample.php

*************
Sample Code
*************

The 'Samples' folder (found two folder levels up) copntains some sample programs that show off the basic functionality of the Address object and also can be used as reference on how to interface with the object.

*******
Updates
*******

The wrapper does not need to be rebuilt for regular updates. Simply replace Address Object (libmdAddr.so) and the data files. However, if there is a new method added, the wrapper will need to be rebuilt to use that new method. 


COPYRIGHT NOTICE

(C) 2014 Melissa Data Corporation. All rights reserved.
